#!/usr/bin/python -O
"""
# ----------------------------------------------------------------------------
# MODULE: taw_time.py		- Time manipulation classes
# ----------------------------------------------------------------------------
# NOTE: taw_ refers to Todd A. Warner (original author).
#
# The classes defined within this module are designed to encapsulate basic
# time constructs and functions.
#
# class Time		- Basic time functions:
#				getUTC()	- Returns Univeral Time
#						  Coordinated
#				getRealTime()	- Returns a readable time.
#
# class Timer		- Basic timer and clocking functions:
#				startTimer()	- Reset and Start the timer.
#				stopTimer()	- Sets finish time to current,
#						  and returns that current
#						  time.
#				checkTimer()	- Check elapsed time without
#						  stopping the timer.
#				resetTimer()	- Reset start and finish times
#						  to 0.
#				sleepTimer( t )	- Timed delay in seconds.
# ----------------------------------------------------------------------------
# License: GPL: http://www.gnu.org/copyleft/gpl.html
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Library General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
# ----------------------------------------------------------------------------
# Created: 20000607	- taw: Todd Warner <taw@pobox.com>
# Updated: 20010326	- taw
# ----------------------------------------------------------------------------
"""
from time import time, ctime




class Time:
    """
    This class defines/implements some generic time manipulation functions.
    All times returned are in seconds.

    Creation:	2000-06-14	-taw: Todd Warner <taw@pobox.com>
    Updated:	2001-03-26	-taw
    """
    def __init__( self ):
        pass

    def getUTC( self ):
	'''
	OUT: same as time.time(). i.e., return number of secs since epoch.
	     UTC stands for Universal Time Coordinated.
	'''
        return time( )
        
    def getRealTime( self ):
	'''
	OUT: Human readable time string for this timezone.
	     e.g., Mon Mar 26 22:21:46 2001
	'''
        return ctime( time( ) )
    # ------------------------------------------------------------- class Time
    # ------------------------------------------------------------------------





class Timer:
    """
    This class defines/implements timer functions. I.e., you can start and
    stop a timer in order to time events within code that imports this.
    All times returned are in seconds.

    Creation:	2000-06-07	-taw: Todd Warner <taw@pobox.com>
    Updated:	2001-03-26	-taw
    """
    def __init__( self ):
        
        self.__start  = 0
        self.__finish = 0
        
    def startTimer( self ):
        """
        This function resets and starts the timer:
            __start set to current time and returned.
            __finish set to 0.
        """
        if self.__finish:
            self.resetTimer( )
        self.__start = time( )
        return self.__start
        
    def stopTimer( self ):
        """
        This function sets the finish time to current and returns it.
        """
        self.__finish = time( )
        return self.__finish
    
    def checkTimer( self ):
        """
        This function checks the elapsed time without stopping the timer.
	Returns:
        	o -1 on error
        	o __finish - __start if timer has been stopped.
        	o current.time() = __start if timer has not be stopped yet.
        """
        if self.__start == 0:
            return -1.0
        else:
            if self.__finish >= self.__start:
                return self.__finish - self.__start
            else:
                return time( ) - self.__start
        
    def resetTimer( self ):
        """
        This function resets the timer variables to 0.
        """
        self.__start  = 0
        self.__finish = 0


    def sleepTimer( self, t ):
	'''
	IN:  Time in seconds (real number) you want to 'sleep' for.
	OUT: A delay of that many seconds (or more if delayed somehow).
	
	This function is especially useful when working in a multithreaded
	application. time.sleep( xxx ) sleeps the whole process. This is an
	undesired side-effect in most cases.
	SO: use time.sleep( xxx ) if you want to sleep a whole process.
	    use Timer.sleepTimer( xxx ) if you want to sleep just a thread.
	'''
	self.startTimer()
	while self.checkTimer() < t:
	    pass
	self.stopTimer()
        return self.checkTimer()
    # ------------------------------------------------------------ class Timer
    # ------------------------------------------------------------------------
        

# ----------------------------------------------------------------------------
# ----------------------------------------------------------------------------
